<?php
// $Id: Credentials.interface.php 73 2007-02-12 03:45:43Z tswicegood $

/**
 * This file contains {@link Credentials} which is part of the PHP Content Repository
 * (phpCR), a derivative of the Java Content Repository JSR-170,  and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */


/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/phpCR.library.php');


/**
 * Base interface for all credentials that may be passed to the
 * {@link Repository::login()} method.
 *
 * Provides a minimal standard method for authenticating against a
 * repository (i.e., using a user ID and password). Additional attributes may
 * be used by the repository to, for example, set a token that can then be
 * passed back and forth once authentication has been completed (thus enabling
 * later authorization without re-authentication). In addition, any class that
 * implements this interface can also, of course, add its own methods to deal
 * with more advanced authentication/authorization mechanisms.
 *
 * PHP Notes: The Java implementation of this extends the class
 * Serializable.  PHP does not have a counterpart, and is not needed, as the
 * language provides the 
 * {@link http://us3.php.net/manual/en/function.serialize.php serialize()}
 * function.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Credentials
{
   /**
    * Returns the user ID.
    *
    * @return string
    */
    public function getUserID();
    
    
   /**
    * Returns the password.
    *
    * Note that this method returns a reference to the password.
    * It is the caller's responsibility to zero out the password information
    * after it is no longer needed.
    *
    * @return string 
    */
    public function getPassword();
    
    
   /**
    * Stores an attribute in this {@link Credentials} instance.
    *
    * <b>PHP Note</b>: The Java implementation requires an object for
    * $value.  Since PHP is a loosely-typed language, it wouldn't
    * make sense to only allow a specific type of value so $value
    * can be any particular type.
    *
    * @param string
    *   Specifies the name of the attribute to set
    * @param mixed
    *   The value to be stored
    */
    public function setAttribute($name, $value);
    
    
   /**
    * Removes an attribute from this {@link Credentials} instance.
    *
    * @param string
    *   Specifies the name of the attribute to remove
    */
    public function removeAttribute($name);
    
    
   /**
    * Returns the value of the NAMED attribute as set by {@link setAttribute()},
    * or NULL if no attribute of the given name exists.
    *
    * See the PHP Note in {@link setAttribute()} for information on the
    * return type here.
    *
    * @param string
    *   Specifies the name of the attribute
    * @return mixed
    *   The value of the attribute,  or NULL if the attribute does 
    *   not exist.
    */
    public function getAttribute($name);
    
    
   /**
    * Returns the names of the attributes available to this {@link Credentials}
    * instance.
    *
    * This method returns an empty array if the credentials instance has no 
    * attributes available to it.
    *
    * @return array
    *   An array containing the names of the stored attributes
    */
    public function getAttributeNames();
}

